Skip to content

feat: support MCP protocol revision 2026-07-28 via the v2 TypeScript SDK - #156

Open
rbuchmayer-pplx wants to merge 1 commit into
perplexityai:mainfrom
rbuchmayer-pplx:sdk-v2-migration
Open

rbuchmayer-pplx wants to merge 1 commit into
perplexityai:mainfrom
rbuchmayer-pplx:sdk-v2-migration

Conversation

@rbuchmayer-pplx

Copy link
Copy Markdown
Collaborator

Summary

Migrates the server from the v1 MCP TypeScript SDK (@modelcontextprotocol/sdk) to the v2 packages (@modelcontextprotocol/server, @modelcontextprotocol/node) and serves MCP protocol revision 2026-07-28 on both transports.

The v1 SDK stops at revision 2025-11-25 and is in maintenance. A client that negotiates 2026-07-28 currently gets 400 Unsupported protocol version on its first request and has to fall back to initialize.

What changed

  • stdio uses serveStdio, so the opening exchange picks the revision per connection.
  • HTTP routes each request with isLegacyRequest:
    • 2026-07-28 requests go to createMcpHandler.
    • Everything else keeps the existing stateless JSON transport, unchanged.
  • Tool schemas are passed as z.object(...) and tool handlers read the v2 request context (ctx.mcpReq).
  • Removed the JSON Schema 2020-12 shim. The v2 SDK emits 2020-12 itself, and the existing test for it still passes.
  • CORS now allows the mcp-protocol-version, mcp-method and mcp-name request headers, which 2026-07-28 clients send from browsers.
  • Dependencies: zod ^4.2.0 (required by the v2 SDK), engines.node >=20.

Behavior changes to be aware of

  • Node 18 is no longer supported. The v2 SDK requires Node 20+.
  • Library consumers of createPerplexityServer get a v2 Server. Code that connects it to a v1 SDK transport needs to move to the v2 packages as well.
  • Calling an unknown tool now returns a JSON-RPC error (-32602) instead of a tool result with isError: true. This comes from the SDK.
  • tools/list output differs in two fields, both from the SDK: input schemas no longer set additionalProperties: false, and tools no longer carry execution.taskSupport. Tool names, descriptions, properties and output schemas are identical, and the server still ignores unknown arguments as before.

Given the Node and library changes, this probably wants a major version bump. I left the version alone so that can go in the release PR.

Testing

  • npm test: 114 passing, including two new tests that connect a real client to the HTTP app, one negotiating 2026-07-28 and one opening with initialize.
  • Compared main and this branch side by side over HTTP:
Request main This branch
initialize (2025-11-25) 200 200
tools/list (2025-11-25) 200 200
server/discover (2026-07-28) 400 200
tools/list (2026-07-28) 400 200
  • stdio: a client in legacy mode negotiates 2025-11-25, and a client in auto mode negotiates 2026-07-28. Both list 4 tools.
  • Live calls to perplexity_search and perplexity_ask succeed over HTTP on both revisions. On 2026-07-28, progress notifications are delivered during perplexity_ask.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant